{
  "openapi": "3.0.3",

  "info": {
    "title": "Cloud File Storage",
    "description": "REST API that provides users with a place to store files and data ",
    "version": "23.1.1"
  },

  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Локальный сервер разработки"
    }
  ],

  "tags": [
    {
      "name": "Authentication/Authorization"
    },

    {
      "name": "Folder"
    },

    {
      "name": "File"
    },

    {
      "name": "Upload"
    },

    {
      "name": "Download"
    }
  ],

  "components" : {
    "schemas" : {
      "folder" : {
        "$ref" : "./resources/schemas/response/folder.json#/folder"
      },

      "file" : {
        "$ref" : "./resources/schemas/response/file.json#/file"
      },

      "error" : {
        "$ref" : "./resources/schemas/response/error.json#/error"
      }
    },

    "parameters": {
      "session" : {
        "$ref" : "./resources/parameters/session.json#/session"
      },

      "folderId" : {
        "$ref" : "./resources/parameters/folderId.json#/folderId"
      },

      "recursed" : {
        "$ref" : "./resources/parameters/recursed.json#/recursed"
      },

      "fileId" : {
        "$ref" : "./resources/parameters/fileId.json#/fileId"
      }
    }
  },

  "paths": {
    "/api/v1/auth/signin" : {
      "post" : {
        "tags": ["Authentication/Authorization"],

        "requestBody" : {
          "content": {
            "application/json" : {
              "schema" : {
               "$ref" : "./resources/schemas/request/signin.json#/signin"
              }
            }
          }
        },

        "responses": {
          "200" : {
            "description": "Успешная аутентификация.",
            "headers": {
              "SESSION" : {
                "$ref" : "#/components/parameters/session"
              }
            },
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "./resources/schemas/response/signin.json#/signin"
                }
              }
            }
          },

          "400" : {
            "description": "Некорректный запрос.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                  "path" : "/api/v1/auth/signin",
                  "message" : "Неверная почта и/или пароль",
                  "statusCode" : 400,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/auth/signup" : {
      "post" : {
        "tags": ["Authentication/Authorization"],

        "requestBody" : {
          "content": {
            "application/json" : {
              "schema" : {
                "$ref" : "./resources/schemas/request/signup.json#/signup"
              }
            }
          }
        },

        "responses": {
          "200" : {
            "description": "Успешная регистрастрация.",
            "headers": {
              "SESSION" : {
                "description": "Сессия пользователя",
                "schema": {
                  "type" : "string"
                }
              }
            },

            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "./resources/schemas/response/signup.json#/signup"
                }
              }
            }
          },

          "400" : {
            "description": "Некорректный запрос.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                    "path" : "/api/v1/auth/signup",
                    "message" : "Bad request.",
                    "statusCode" : 400,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/auth/logout" : {
      "get" : {
        "tags": ["Authentication/Authorization"],
        "responses": {
          "200" : {
            "description": "Успешное прекращение сеанса работы в качестве аутентифицированного пользователя."
          }
        }
      }
    },

    "/api/v1/cloud/folder": {
      "post" : {
        "tags": ["Folder"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          }
        ],

        "requestBody" : {
          "content": {
            "application/json" : {
              "schema" : {
                "$ref" : "./resources/schemas/request/createFolder.json#/createFolder"
              }
            }
          }
        },
        
        "responses": {
          "201" : {
            "description": "Успешно созданная папка.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "./resources/schemas/response/folder.json#/folder"
                }
              }
            }
          },

          "400" : {
            "description": "Некорректный запрос.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                  "path" : "/api/v1/cloud/folder",
                  "message" : "Bad request.",
                  "statusCode" : 400,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },
    
    "/api/v1/cloud/folder/home" : {
      "get" : {
        "tags": ["Folder"],

        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          }
        ],

        "responses": {
          "200" : {
            "description": "Информация о домашней папке пользователя",
            "content": {
              "application/json": {
                "schema" : {
                  "$ref" : "#/components/schemas/folder"
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                    "path" : "/api/v1/cloud/folder/adsf",
                    "message" : "Not authenticated!",
                    "statusCode" : 401,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/cloud/folder/{folderId}": {
      "get": {
        "tags": ["Folder"],
        
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/folderId"
          }
        ],

        "responses": {
          "200" : {
            "description": "Информация о коталоге.",
            "content": {
              "application/json": {
                "schema" : {
                  "$ref" : "#/components/schemas/folder"
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                    "path" : "/api/v1/cloud/folder/adsf",
                    "message" : "Not authenticated!",
                    "statusCode" : 401,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },

          "404" : {
            "description": "Директория не найдена.",
            "content": {
              "application/json" : {
                "schema" : {
                    "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/folder/adsf",
                  "message" : "Not found directory!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      },

      "delete" : {
        "tags": ["Folder"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/folderId"
          },
          {
            "$ref": "#/components/parameters/recursed"
          }
        ],
        "responses": {
          "204" : {
            "description": "Возвращает пустой ответ, когда папка успешно удалена или перемещена в корзину."
          },
          "400" : {
            "description": "Папка содержит элементы, используйте query параметр `recursed=true` для рекурсивного удаления.",
            "content": {
              "application/json" : {
                
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/folder/asfasd3",
                  "message" :  "Bad request.",
                  "statusCode" : 400,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },

          "404" : {
            "description": "Удаляемая папка не была найдена.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/folder/asfasd3",
                  "message" : "The directory is not empty!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/cloud/folder/{folderId}/items": {
      "get": {
        "tags": ["Folder"],
        
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/folderId"
          }
        ],

        "responses": {
          "200" : {
            "description": "Список файлов и каталогов определенной папки.",
            "content": {
              "application/json": {
                "schema" : {
                  "$ref" : "./resources/schemas/response/items.json#/items"
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                    "path" : "/api/v1/cloud/folder/adsf",
                    "message" : "Not authenticated!",
                    "statusCode" : 401,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },

          "404" : {
            "description": "Директория не была найдена не найдена.",
            "content": {
              "application/json" : {
                "schema" : {
                    "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/folder/adsf",
                  "message" : "Not found directory!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/cloud/file/{fileId}" : {
      "get": {
        "tags": ["File"],
        
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/fileId"
          }
        ],

        "responses": {
          "200" : {
            "description": "Информация о файле.",
            "content": {
              "application/json": {
                "schema" : {
                  "$ref" : "#/components/schemas/file"
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example" : {
                    "path" : "/api/v1/cloud/file/adsf",
                    "message" : "Not authenticated!",
                    "statusCode" : 401,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },

          "404" : {
            "description": "Файл не найден.",
            "content": {
              "application/json" : {
                "schema" : {
                    "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/file/adsf",
                  "message" : "Not found file with id - adsf!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      },

      "delete" : {
        "tags": ["File"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/fileId"
          }
        ],
        "responses": {
          "204" : {
            "description": "Возвращает пустой ответ, когда файл успешно удалён или перемещена в корзину."
          },
          
          "404" : {
            "description": "Удаляемый файл не был найден.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/file/asfasd3",
                  "message" : "Not found file with id - asfasd3!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

    "/api/v1/cloud/upload/file" : {
      "post" : {
        "tags": ["Upload"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          }
        ],

        "requestBody" : {
          "content": {
            "multipart/form-data" : {
              "schema" : {
                "$ref" : "./resources/schemas/request/uploadFile.json#/uploadFile"
              }
            }
          }
        },

        "responses": {
          "200" : {
            "description": "Файл успешно загружен.",
            "content": {
              "application/json" :{
                "schema" : {
                  "$ref" : "#/components/schemas/file"
                }
              }
            }
          },

          "400" : {
            "description": "Некорректный запрос.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref": "#/components/schemas/error"
                },
                "example" : {
                  "properties": {
                    "path" : "/api/v1/cloud/upload/file",
                    "message" : "Bad request!",
                    "statusCode" : 400,
                    "timestamp" : "2024-04-14T17:15:46.609+00:00"
                  }
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref": "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/upload/file",
                  "message" : "Not authenticated!",
                  "statusCode" : 401,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },

   "/api/v1/cloud/download/file/{fileId}" : {
      "get" : {
        "tags": ["Download"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/fileId"
          }
        ],
        "responses": {
          "200" : {
            "description": "Файл найден и успешно преобразован в массив байт.",
            "content": {
              "application/octet-stream" : {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "example" : "�PNGIHDR�-DW0��DtEXtmxfile%3Cmxfile%20host%3D%22app.diagrams.net%22%20modified%3D%222024-04-16T14%3A26%3A44.401Z%22%20agent%3D%22Mozilla%2F5.0%20(X11%3B%20Linux%20x86_64%3B%20rv%3A124.0)%20Gecko%2F20100101%20Firefox%2F124..."
                }
              }
            }
          },
          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref": "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/download/file/asdf",
                  "message" : "Not authenticated!",
                  "statusCode" : 401,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },
          "404" : {
            "description": "Файл не найден.",
            "content": {
              "application/json" : {
                "schema" : {
                    "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/download/file/asdf",
                  "message" : "Not found file with id - adsf!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    },
    
    "/api/v1/cloud/download/folder/{folderId}" : {
      "get" : {
        "tags": ["Download"],
        "parameters": [
          {
            "$ref": "#/components/parameters/session"
          },
          {
            "$ref": "#/components/parameters/folderId"
          }
        ],
        "responses": {
          "200" : {
            "description": "Директория найдена и успешно запакована в .zip архив, а после преобразована в массив байт.",
            "content": {
              "application/octet-stream" : {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "example" : "�PNGIHDR�-DW0��DtEXtmxfile%3Cmxfile%20host%3D%22app.diagrams.net%22%20modified%3D%222024-04-16T14%3A26%3A44.401Z%22%20agent%3D%22Mozilla%2F5.0%20(X11%3B%20Linux%20x86_64%3B%20rv%3A124.0)%20Gecko%2F20100101%20Firefox%2F124..."
                }
              }
            }
          },

          "401" : {
            "description": "Требуеся аутентификация.",
            "content": {
              "application/json" : {
                "schema" : {
                  "$ref": "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/download/folder/asdf",
                  "message" : "Not authenticated!",
                  "statusCode" : 401,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          },
          "404" : {
            "description": "Директория не найден.",
            "content": {
              "application/json" : {
                "schema" : {
                    "$ref" : "#/components/schemas/error"
                },
                "example": {
                  "path" : "/api/v1/cloud/download/folder/asdf",
                  "message" : "Not found folder with id - adsf!",
                  "statusCode" : 404,
                  "timestamp" : "2024-04-14T17:15:46.609+00:00"
                }
              }
            }
          }
        }
      }
    } 
  }
}